//+------------------------------------------------------------------+
//|                                                        Panel.h    |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include "WndObj.h"                                  // 窗口对象基类（提供基础控件能力）
#include <ChartObjects/ChartObjectsTxtControls.h>     // 图表文本控件类（包含 CChartObjectRectLabel）

//+------------------------------------------------------------------+
//| CPanel 类：MQL5 面板控件类                                       |
//| 核心能力：封装图表对象 CChartObjectRectLabel，提供矩形区域展示功能，|
//|           支持背景色、边框样式配置，常用于作为其他控件的容器或装饰性区域 |
//| 适用场景：对话框背景、控件分组容器、分隔区域、装饰性边框等           |
//+------------------------------------------------------------------+
class CPanel : public CWndObj
  {
private:
   CChartObjectRectLabel m_rectangle;       // 图表矩形标签对象（底层实现，负责绘制面板）
   ENUM_BORDER_TYPE  m_border;              // 边框样式（BORDER_FLAT/ BORDER_RAISED 等）

public:
   //----------------------------------------------------------------
   // 构造与析构函数
   //----------------------------------------------------------------
   /**
    * @brief 构造函数：初始化面板默认状态
    * @details 初始化边框样式为扁平边框（BORDER_FLAT），其他属性使用父类默认值
    */
                     CPanel(void);

   /**
    * @brief 析构函数：清理面板资源
    * @details 依赖父类 CWndObj 的析构逻辑，自动释放底层图表对象 m_rectangle
    */
                    ~CPanel(void);

   //----------------------------------------------------------------
   // 控件创建：在图表上创建面板
   //----------------------------------------------------------------
   /**
    * @brief 在指定图表位置创建面板控件
    * @param chart [in] 目标图表ID（0 表示当前活跃图表）
    * @param name [in] 控件唯一标识名（图表内不可重复）
    * @param subwin [in] 绑定的子窗口编号（0 = 主窗口，≥1 = 指标子窗口）
    * @param x1 [in] 左上角X坐标（像素，相对于图表窗口）
    * @param y1 [in] 左上角Y坐标（像素）
    * @param x2 [in] 右下角X坐标（像素）
    * @param y2 [in] 右下角Y坐标（像素）
    * @return bool - 创建结果：true=成功（父类初始化+底层对象创建完成），false=失败
    */
   virtual bool      Create(const long chart,const string name,const int subwin,const int x1,const int y1,const int x2,const int y2);

   //----------------------------------------------------------------
   // 边框样式配置：设置/获取面板边框类型
   //----------------------------------------------------------------
   /**
    * @brief 获取当前边框样式
    * @return ENUM_BORDER_TYPE - 边框样式（如 BORDER_FLAT 扁平边框、BORDER_RAISED 凸起边框等）
    */
   ENUM_BORDER_TYPE  BorderType(void)       const;

   /**
    * @brief 设置面板的边框样式
    * @param type [in] 目标边框样式（ENUM_BORDER_TYPE 枚举值）
    * @return bool - 设置结果：true=成功（更新底层对象边框样式），false=失败
    */
   bool              BorderType(const ENUM_BORDER_TYPE type);

protected:
   //----------------------------------------------------------------
   // 控件属性更新处理器（保护，仅子类可重写）
   //----------------------------------------------------------------
   /**
    * @brief 文本更新处理器（文本变化时同步到底层对象）
    * @return bool - 处理结果：true=成功（更新 m_rectangle 的描述文本），false=失败
    * @note 面板文本通常用于内部标识，默认不显示在视觉上
    */
   virtual bool      OnSetText(void);

   /**
    * @brief 背景颜色更新处理器（颜色变化时同步到底层对象）
    * @return bool - 处理结果：true=成功（更新 m_rectangle 的背景颜色），false=失败
    */
   virtual bool      OnSetColorBackground(void);

   /**
    * @brief 边框颜色更新处理器（颜色变化时同步到底层对象）
    * @return bool - 处理结果：true=成功（更新 m_rectangle 的边框颜色），false=失败
    */
   virtual bool      OnSetColorBorder(void);

   //----------------------------------------------------------------
   // 控件生命周期事件处理器（保护，仅子类可重写）
   //----------------------------------------------------------------
   /**
    * @brief 创建完成事件回调（控件创建后触发）
    * @return bool - 处理结果：true=成功（底层对象初始化完成），false=失败
    */
   virtual bool      OnCreate(void);

   /**
    * @brief 显示事件回调（控件从隐藏变为显示时触发）
    * @return bool - 处理结果：true=成功（在所有时间帧显示），false=失败
    */
   virtual bool      OnShow(void);

   /**
    * @brief 隐藏事件回调（控件从显示变为隐藏时触发）
    * @return bool - 处理结果：true=成功（在所有时间帧隐藏），false=失败
    */
   virtual bool      OnHide(void);

   /**
    * @brief 移动事件回调（控件位置变化时触发）
    * @return bool - 处理结果：true=成功（更新底层对象位置），false=失败
    */
   virtual bool      OnMove(void);

   /**
    * @brief 尺寸变化事件回调（控件大小变化时触发）
    * @return bool - 处理结果：true=成功（更新底层对象尺寸），false=失败
    */
   virtual bool      OnResize(void);

   /**
    * @brief 属性变化事件回调（控件属性更新时触发）
    * @return bool - 处理结果：true=成功（同步所有属性到底层对象），false=失败
    */
   virtual bool      OnChange(void);
  };
//+------------------------------------------------------------------+